Skip to main content

1.1 - What is python-sc2

python-sc2 is a Python library that enables you to program an artificial intelligence (AI) to play the real-time strategy game StarCraft II. It serves as a high-level, easy-to-use wrapper around Blizzard's official StarCraft II Machine Learning API.

The official API is powerful but complex to work with directly. python-sc2 simplifies this by handling the low-level communication, allowing you to focus on strategy and logic rather than API boilerplate.

Think of the architecture like this:

+-------------------------+
|   Your Bot Logic        |  <-- You write this in Python!
|   (strategy.py)         |
+-------------------------+
           ^
           | (Uses functions like "unit.attack()" or "self.expand_now()")
           v
+-------------------------+
|   python-sc2 Library    |  <-- This library simplifies commands.
+-------------------------+
           ^
           | (Translates simple functions into complex API calls)
           v
+-------------------------+
|   StarCraft II API      |  <-- The official, low-level interface from Blizzard.
+-------------------------+
           ^
           | (Communicates with the game engine)
           v
+-------------------------+
|   StarCraft II Game     |
+-------------------------+

Core Capabilities Checklist​

The library provides you with the tools to perform all the essential actions a human player can.

  • Access Game State: Read information about the map, your resources (minerals, vespene, supply), and the status of all visible units.
  • Issue Unit Commands: Tell your units to move, attack, patrol, hold position, or use special abilities.
  • Manage Economy: Command workers to gather resources, build structures, and expand to new bases.
  • Automate Production: Train units from production structures and research upgrades from tech buildings.
  • Respond to Events: Execute code at the start of the game, at every game step, when a unit is created, and more.

Why Use python-sc2?​

The main goal is to accelerate development and make it more intuitive. Here’s a quick comparison:

FeatureDirect API InteractionUsing python-sc2
Game StateRequires manually parsing complex data structures (Protobufs).Provides clean, object-oriented access (e.g., self.units, self.minerals).
Unit CommandsInvolves constructing detailed API queries with unit tags and ability IDs.Offers simple, readable methods (e.g., worker.gather(mineral_field)).
SetupDemands significant boilerplate code just to connect to the game.Handles the entire game connection and setup process for you.
Learning CurveSteep. Requires deep knowledge of the StarCraft II API.Gentle. Allows you to build a functional bot within minutes.

In short, python-sc2 is the ideal starting point for anyone—from hobbyists and students to AI researchers—looking to create StarCraft II bots with Python. It provides the power of the official API without the steep learning curve.